wildpocketsfandomcom-20200213-history
Programming Manual Chap. 15
Wild Pockets provides a file server, where all models, textures, scripts, and other assets are stored. Every Wild Pockets account comes with a folder on the file server. The file server provides several advantageous and unusual features, described in this section. File Server Paths When an asset is stored the file server, it has a pathname. Pathnames always start with a Wild Pockets username. For example, if your username is "Bob", and you upload a texture called "Brick.jpg" to your server folder, the pathname of that asset is "Bob/Brick.jpg". When loading an asset from a game, you must provide the full path: object:setTexture("Bob/Brick.jpg") Pathnames in Wild Pockets are similar to pathnames in Unix or Windows. Directories are separated by forward slashes. The legal characters allowed in a filename are somewhat restricted: letters, numbers, spaces, dashes, underscores, and a few other punctuation marks. For the most part, all filenames must have valid extensions (however, there are legacy files on the file server that were created before this rule was put into place). Your game can load assets that belong to other users, if they have granted you permission. To do this, just put the correct paths into your scripts: SceneManager.createObject("Alice/Dragon.geom") SceneManager.createObject("Steve/Lizard.geom") SceneManager.createObject("Fred/Snake.geom") Or, use a drag-and-drop tool such as the library or the file browser to find the asset and drag it into your game. The File Browser The development environment contains a menu item: Folders/Open Server Folder. This opens up a file browser that shows you the contents of your folder on the server. The file browser functions much like any other operating system's file browser. You can view the contents of your directory, sort it by name or type, and move from directory to directory. The file browser has a right-click menu that allows you to delete, rename, and do other manipulations to files. Version Numbers When you upload a file to the server, the server gives it a version number 0. The next time you upload that same file, it gives it the version number 1. If you then delete the file, you have actually created a blank version - version 2 is empty. If you upload the file again, you have now created version 3. The server remembers all versions indefinitely. (The file browser only shows you the latest version.) Storing old versions is very useful for backups: we plan to provide a tool that shows your files as they were at a particular time. This will allow you to recover from any disaster. This tool is not implemented yet, until it is written, we are happy to help our users restore files manually. We can restore to any time or date. In addition to backups, versioning is particularly useful for ensuring that games don't break. When you test your game and the game loads an asset, the development environment records what version of the asset was used. If you then choose to publish the game, the published game will continue to use the same version of the asset that you saw in testing mode -- even if a more recent version of the asset is written to the file server. This means that assets can be updated on the file server without any risk of published games that use those assets breaking. Version locking is described in greater detail in a chapter of its own. Legal File Formats The file server will only store files in certain formats: you cannot upload files unless they are one of the recognized file formats understood by Wild Pockets. Any file that is not in a valid format will be ignored by the file-uploading tool. You must use the correct extension, or Wild Pockets will ignore the file. Here are the understood formats: The Local Mirror The development environment creates a folder on your hard drive whose purpose is to mirror portions of the file server. Usually, you would mirror your own directory, but you can mirror other directories as well if you have been given access. To view the local mirror of your server folder, click Folders/Open Local Folder. The directory will open using your operating system's standard file browser. The local folder is meant to contain identical files to those in your server folder. When using Wild Pockets, scripts are created by using your programmer's editor to save them into the local folder. Then, a synchronization tool we provide is used to upload the script to the server folder. Models are created the other way around: the exporter writes to the server folder. Then, the synchronization tool is used to download the file to the local folder. Running the sync tool causes all newly-created files, regardless of which side they were created on (server or local), to be copied to the other side. If you edit a file and update it, then the sychronization tool is smart enough to find the edit and propagate the modification to the other side. No matter what you do to either the server or local folder, the sync tool will find the alteration and propagate it to the other side. If you modify either the server or local folder, and forget to run the sync tool, then the server folder and local folders will differ. This is no problem: the development environment loads assets from both the local and server folders. It is smart enough to find the most-recent version, regardless of whether it was altered on the server side or the local side. The upshot is this: you can edit files in the local folder, or on the server folder, or both, and things will continue to "just work." You can run the synchronization tool whenever you feel like it, and things will "just work." Using the Synchronization Tool To invoke the sync tool, click Folders/Sync username. This will attempt to mirror the entire contents of your server folder to your local folder, and vice-versa. The sync tool will scan your local folder and your server folder to see what has been altered. It is smart enough to find alterations on either side. When it is done scanning, it will present you with a list of files that have been altered. For each alteration, it will present you with the necessary action to propagate the change: upload the local copy, download the server copy, or delete both copies. The listing produced by the synchronization tool looks like this: The sync tool will always try to propagate your edits. But there are some situations where you might not want to stop it from doing that. For example, suppose that the sync tool tells you that you edited a file locally, and the modifications need to be uploaded. You examine the file and realize that sure enough, you did edit it, but it was an accident. In that case, you can ask the sync tool to download the file instead of upload it - effectively overwriting your unintentional modifications. To do this, click the download-button next to the file name. This will force the sync tool to download the file instead of uploading it. There is one situation where the sync tool doesn't know what to do: if you alter a file in the server folder (say, using the file explorer), and alter the same file in the local folder. In that case, you have edits on both sides, and it doesn't know which set of edits to propagate. In that case, the sync tool will show you that there is a conflict, and will ask you what you want to do. You answer by clicking the upload-button, download-button, or delete-button next to the file name. When you hit the "OK" button, the sync tool will initiate uploads and downloads. It will take a little time for all the transfers to complete. The sync tool will show you its progress. Syncing other Folders Normally, you just synchronize your own folder. But on occasion, you may want to sync files that belong to other users to your own hard drive. You can only do this if you have been granted permission. To do this, use the Folders/Sync Other... menu item, and type in the name of the folder you wish to synchronize. Sometimes, syncing somebody else's folder is a part of your development process. In that case, you may wish to add a menu item to the Folders menu to allow you to synchronize that folder without having to type its name in over and over. To do this, use the Folders/Configure File Sync configuration panel. If your own folder gets very large, it may take quite a bit of time to sync the whole thing. In that case, it may be desirable to sync just a subfolder. You can do this using Sync Other or Configure File Sync. Permission Grants Other users can access your files if you grant them permission. There are several kinds of rights you can grant: *''Read Access''. The right to download the asset to their local folder using the sync tool. Of course, once they have their own copy of it, they can easily do whatever they want with it. Read access also grants the ability to view a lua script. Read Access implies Use Access and Preview Access. *''Use Access''. The right to load the asset from inside a published game. If you grant somebody use access, they can publish games that include that asset. Use access does not enable them to download their own copy to their local folder, nor does it allow them to view the source code of a lua script. Use Access implies Preview Access. *''Preview Access''. The right to load the asset from inside the development and testing environment, or in the model viewer. Preview access is generally granted if you want somebody to be able to try the asset before buying use-access from you. It enables them to experiment with the asset, but it doesn't enable them to publish a game with the asset. *''Play access''. The right to play a game. This right only applies to scene files (a scene file is the master file in a game). Generally, when you are about to publish a game, you grant play access to everyone. *''Write Access''. The right to overwrite the asset. Of course, you should only grant this to members of your development team. Permission grants can be controlled via the file browser (right click a file or folder), or via the gallery publishing page. Every file has an access control list. A typical access control list might look like this: Here, you have granted David all rights except the ability to alter the file (no write access). The token "Everyone" is a special word that grants rights to all Wild Pockets users. In this case, the access control list grants everyone preview-only access. If you grant permissions on a folder, then you have granted rights to all the files inside the folder. For example, if you're an easygoing free software developer, you might decide to grant Read access of your main folder to everyone. If you do that, everyone on the system will be able to experiment with, use, and download your files. If you grant permissions on a folder, and also to a file in that folder, the rights are cumulative. For example, if you grant read-access to the entire folder, and write access to just one file, then that file has both read and write access. This is important: you cannot remove access by creating grants: you can only add access by creating grants.